package com.alexeyhanin.tapestry.goodies.util.select;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * InjectSelectModel extends component with additional properties that represents select model based on values in
 * {@link java.util.List list} field it is bound to.
 * <h3>Usage:</h3>
 * <ol>
 * <li><p>Bind {@literal @InjectSelectModel} to a property
 * <pre>
 * public class Countries {
 *     {@literal @InjectSelectModel}(id = "countryId", label = "name")
 *     private List&lt;Country&gt; countries;
 * }
 * </pre>
 * </li>
 * <li><p>Set model and encoder attributes to &lt;select&gt; element in template
 * <pre>
 * &lt;t:select t:id="country"
 *     model="countriesSelectionModel"
 *     encoder="countriesValueEncoder"/&gt;
 * </pre>
 * </li>
 * </ol>
 * Based on approach <a href="http://wiki.apache.org/tapestry/Tapestry5AnotherSelectWithObjects">described</a>
 * in Tapestry 5 HowTos.
 *
 * @author aha
 * @since 2009.5.11
 *        $Id: InjectSelectModel.java 16 2009-11-30 18:08:12Z gagarin61 $
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface InjectSelectModel {

    /**
     * Comma-separated list of properties distinctly identifying option value separated.
     *
     * @return property {@link String string}
     */
    String id();

    /**
     * Label property.
     *
     * @return property name
     */
    String label() default "";

    /**
     * Allows to represent label as a formatted string. Properties must be enclosed in curly brackets.
     *
     * @return format {@link String string}
     */
    String labelFormat() default "";
}
